Objective

• Fixes Configurable error handling in commands #2004
• Fixes EntityCommands should have methods to fail gracefully #3845
• Fixes Potential surprising "entity does not exist" panic due to asynchronous command execution #7118
• Fixes Commands should be infallible whenever possible #10166

Solution

Added the following Commands:

• ignore_on_error
• log_on_error (sends messages using info!)
• warn_on_error (sends messages using warn!)
• panic_on_error

and the following EntityCommands:

• ignore_if_missing
• log_if_missing
• warn_if_missing
• panic_if_missing

These change how subsequent commands will respond if errors occur.

Internally:

• Added a failure_handling_mode field to Commands.
• When a fallible Command or an EntityCommand is queued, this field is sent with it.
• Fallible Commands should check for errors themselves.
• When any EntityCommand is applied, it automatically checks if the entity exists.
• If an error occurs, the command matches against failure_handling_mode to determine how to respond.

Showcase

#[derive(Component)]
struct X;

let mut world = World::default();

let mut queue_a = CommandQueue::default();
let mut queue_b = CommandQueue::default();

let mut commands_a = Commands::new(&mut queue_a, &world);
let mut commands_b = Commands::new(&mut queue_b, &world);

let entity = commands_a.spawn_empty().id();

commands_a.entity(entity).despawn();
commands_b.entity(entity).warn_if_missing().insert(X);

queue_a.apply(&mut world);
queue_b.apply(&mut world); // Doesn't panic

Review Notes

The real changes are all in system/commands/mod.rs and world/mod.rs.
All the other files are just returning some commands to their old behavior:

• despawn() -> warn_if_missing().despawn()
• remove() -> ignore_if_missing().remove()

These two are the only commands that both 1) didn't already panic by default and 2) were used internally (according to VS Code's "Find All References" anyway).
They might not all need to be kept non-panicking, I just didn't want to regress anything.

Bikeshedding

• ignore vs silent vs something else?
• failure_handling_mode vs failure_response vs something else? (Used to be failure_mode, but that's wrong)
• info! vs debug!?

Possible Additions / Future PRs

• Deprecate try_ variants of commands
  • I added some comments explaining the change and directing the user to the normal variants, but held off on deprecating since AFAIK that's usually a separate PR.
• Location tracking
  • Just call Location::caller in the user-facing command (if not set to ignore) and pass it in, so the user can see exactly which command caused an error. Didn't seem to hurt performance meaningfully in my testing, but maybe I'm not the best at benchmarking.
• Generalized errors for Commands using Result
  • We can't return a Result from a command to the caller, but we could wrap commands in something that handles any Err returned from the internal function call.

Migration Guide

The following commands that used to fail silently will now panic by default:

• EntityCommands::remove
• EntityCommands::remove_by_id
• EntityCommands::remove_with_requires
• EntityCommands::clear
• EntityCommands::retain
• EntityCommands::observe
• EntityEntryCommands::and_modify

Use ignore_if_missing to achieve the previous behavior:

commands.entity(entity).ignore_if_missing().clear();

The command EntityCommands::despawn used to warn upon failure and will now panic by default.
Use warn_if_missing to achieve the previous behavior:

commands.entity(entity).warn_if_missing().despawn();

try variants of commands are unchanged and will always fail silently; these will be removed in the future.